.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH ddcutil 1 "2024-01-11"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
ddcutil \- Query and change monitor settings
.SH SYNOPSIS
\fBddcutil\fP [\fIoptions\fP] command [\fIcommand-arguments\fP] [\fIoptions\fP]

Options can be written either before or after the command and its arguments.

.\" ALT USING .SY .OP
.\" .SY
.\" .OP \-abcde
.\" .OP \-b busno
.\" .OP \-d|--display dispno
.\" command command-arguments
.\" .YS


.SH DESCRIPTION
\fBddcutil\fP is used to query and change monitor settings.  
The settings that can be controlled by \fBddcutil\fP are, generally speaking, those that can be changed using the buttons
on a monitor and its on screen display.  The specific settings vary from monitor to monitor.

\fBddcutil\fP communicates with monitors that implement the Monitor Control Command Set (MCCS) using the DDC/CI protocol on an I2C bus.  
Normally, the video driver for the monitor exposes the I2C bus as devices named /dev/i2c-n.  
Alternatively, \fBddcutil\fP can communicate with monitors that use USB to communicate MMCS, provided the monitors meet the USB Monitor Control Class Specification.

The Monitor Control Command Set describes a collection of Virtual Control Panel (VCP) features that a monitor can implement.
Each feature is identified using a single byte.  For example, feature x10 is the brightness control. 

Common use cases include changing monitor brightness and color.  Using scripts, the changes can be effected by keystrokes,
or in response to the time of day.  
Another common use case is to switch the monitor input source. 

A more complex  use case for \fBddcutil\fP is as part of color profile management.  
Monitor calibration is relative to the monitor color settings currently in effect, e.g. red gain.  
\fBddcutil\fP allows color related settings to be saved at the time a monitor is calibrated, 
and then restored when the calibration is applied.


This man page describes \fBddcutil\fP commands and options most important to the typical user. 
For complete documentation, use the \fI--help\fP option or see the web site
.UR http://www/ddcutil.com
.UE .
If option \fI--verbose\fP is specifeid in conjunction with \fI--help\fP, more extensive help on option arguments is shown.

Option \fI--hh\fP shows all options recognized by \fBddcutil\fP. These include deprecated option names (which have been replaced
by more descriptive names), experimental options, and options only of interest to developers.

.SH RESTRICTIONS
\fBddcutil\fP does not support laptop monitors, which do not implement DDC/CI.


.PP
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics, 
.\" respectively.


.\" .B ddcutil
.\" .I command 
.\" .R [
.\" .I command-arguments
.\" .R ] [
.\" .I options
.\" .R ]

.SH COMMANDS
.SS Primary Commands
These are the most used \fBddcutil\fP commands.
.TP
.B "detect "
Find monitors that have a Virtual Control Panel.
.TP
\fBvcpinfo\fP [ \fIfeature-code\fP | \fIfeature-group\fP ]
Describe VCP feature codes. as defined in the MCCS specification.
Use option \fI--verbose\fP to see values for Non-Continuous features.
.TP 
.B "capabilities "
Query the monitor's capabilities string 
.TP
\fBgetvcp\fP [ \fIfeature-code\fP | \fIfeature-group\fP ] ...
Report a VCP feature value, or a group of feature values.
More than one feature code can be specified. However feature codes and groups cannot be combined.
.TP
\fBsetvcp\fP \fIfeature-code\fP [+|-] \fInew-value\fP ...
Set a VCP feature value.  If + or - is specified, it must be surrounded by blanks, and indicates a relative value change of a continuous VCP feature.
Multiple feature/value pairs (with or without [+|1]) can be specified.
.SS Secondary Commands 
These commands address special situations.
.TP
.BI "dumpvcp " filename
Save color profile related VCP feature values in a file.
If no file name is specified, one is generated and the file is saved in $HOME/.local/share/ddcutil,
.TP 
.BI "loadvcp " filename
Set VCP feature values from a file.  The monitor to which the values will be applied is determined by the monitor identification stored in the file. 
If the monitor is not attached, nothing happens.
.TP
.B "scs "
Issue DDC/CI Save Current Settings request. Most monitors do not implement this command.
A few require it for values changed by \fBsetvcp\fP to take effect.
.TP
.B "chkusbmon "
Tests if a hiddev device may be a USB connected monitor, for use in udev rules.
.TP
.BI "discard " "all|capabilities|dsa " cache[s]
Discard cached files used for performance improvement.
.TP
.B "traceable-functions"
Lists functions that can be specifically traced using an option like \fI--trcfunc\fP or \fI--trcfrom\fP
.TP
.B "noop "
Do not execute a command.  Just process options.
.SS Diagnostic commands
These commands  diagnose issues in the system configuration that affect 
\fBddcutil\fP operation,  
and that gather information for remote problem diagnosis.
.TP
.B "environment "
Probe the \fBddcutil\fP installation environment.
.TP
.B "usbenv "
Probe USB aspects of the \fBddcutil\fP installation environment.
.TP
.B "probe "
Explore the capabilities and features of a single monitor. 
.TP
.B "interrogate "
Collect maximum information for problem diagnosis. Includes the output of \fBddcutil environment --verbose\fP for each detected monitor, 
the output of \fBddcutil capabilities --verbose\fP and \fBddcutil probe --verbose\fP.

.PP

.SH COMMAND ARGUMENTS

.I feature-code
.sp
A feature-code is specified by its 2 character hex feature number, with or without a leading "0x", e.g.
0x10, 10 
.sp 2
.I feature-group
.sp 2
The following are the most useful feature groups.  For a complete list,  use the \fB--help\fP option.
.TP
.BR ALL|KNOWN
All feature codes understood by \fBddcutil\fP
.TQ 
.B COLOR
Scan color related feature codes
.TQ
.B PROFILE 
Subset of color related feature codes that are saved and restored by \fBdumpvcp\fP and \fBloadvcp\fP
.TQ
.B SCAN
Scan all possible feature codes 0x00..0xff, except those known the be write-only
.PP
Feature group names can be abbreviated to the first 3 characters.  Case is ignored. e.g. "COL", "pro".

.I new-value
.sp
Normally, this is a decimal number in the range 0..255, or a hexadecimal number in the range x00..xff.
More generally, this is actually a two byte value, i.e. x00..xffff, and a few features on some monitors use this 
extended range.


.\" .TP inserts a line before its output, .TQ does not 


.SH OPTIONS

.PP
Options that control the amount and form of output.
.TQ
.B "-t, --terse, --brief"
Show brief detail.  For command \fBgetvcp\fP, the output is in machine readable form.
.TQ
.B -v, --verbose
Show extended detail

.PP
Options for program information.
.TQ
.B "-V, --version"
Show program version.
.TQ
.B "--settings"
Report option settings in effect.
.TQ
.BR -h , --help 
Show program help.
.TQ
.B "--hh"
Show program help including hidden options. Hidden options include alternative option names,
experimental and deprecated options, and ones for debugging.

.PP
Options for monitor selection.  If none are specified, the default is the first detected monitor.
Options \fB--mfg\fP, \fB--model\fP and \fB--sn\fP can be specified together.
.TQ
.BR "-d , --dis , --display " , 
.I display-number 
logical display number (starting from 1)
.TQ
.BR "-b,--bus "
.I bus-number
I2C bus number
.TQ
.BR "--hiddev "
.I device number
hiddev device number
.TQ
.BI "-u,--usb " "busnum.devicenum"
USB bus and device numbers
.TQ
.B -g,--mfg
3 letter manufacturer code
.TQ
.B -l,--model
model name
.TQ
.B -n,--sn
serial number.  (This is the "serial ascii" field from the EDID, not the binary serial number.)
.TQ 
\fB-e,--edid\fP
256 hex character representation of the 128 byte EDID.  Needless to say, this is intended for program use.

.PP
Feature selection filters
.TQ
.B "-U, --show-unsupported"
Normally, \fBgetvcp\fP does not report unsupported features when querying a feature-group.  This option forces output. 
.TQ
.B "--show-table | --no-table
Normally, \fBgetvcp\fP does not report Table type features when querying a feature-group.  \fB--show-table\fP forces output.   \fB--no-table\fP is the default.
.TQ
.B "--rw, --ro, --wo"
Limit \fBgetvcp\fP or \fBvcpinfo\fP output to read-write, read-only, or (for \fBvcpinfo\fP) write-only features.



.PP
Options for diagnostic output
.TQ
.B --ddcdata
Reports DDC protocol errors.  These may reflect I2C bus errors, or deviations by monitors from the MCCS specification.
Formerly named \fB--ddc\fP,
.TQ
.BR --stats " [" all | errors | tries | calls | elapsed | time ]
Report execution statistics.
I2C bus communication is inherently unreliable.  It is the responsibility of the program using the bus, i.e. \fBddcutil\fP,
to manage retries in case of failure.  This option reports retry counts and various performance statistics.
If no argument is specified, or ALL is specified, then all statistics are 
output.  ELAPSED is a synonym for TIME.  CALLS implies TIME.
.br Specify this option multiple times to report multiple statistics groups.
.TQ
.BR --vstats  " [" all | errors | tries | calls | elapsed | time ] 
Like \fB--stats\fP, but includes per-display statistics.
.TQ
.BR --istats  " [" all | errors | tries | calls | elapsed | time ] 
Like \fB--vstats\fP, but includes additional internal information.
.TQ
.BI --syslog " [" debug | verbose | info | notice | warn | error | never " ]"
Write messages of the specified or more urgent severity level to the system log.
The \fBddcutil\fP default is \fBWARN\fP. The \fBlibddcutil\P default is \fBNOTICE\fP.
./" .TQ
./" .BI "--libddcutil-trace-file" file name
./" Direct trace output to the specified file instead of the terminal. This is a \fBlibddcutil\fP only option.
./" .TQ
./" .BI "--trace" trace-class-name
./" Trace all functions in a trace class.  For a list of trace classes, use \fI--help --verbose\fP.
./" .TQ
./" .BI "--trcfunc" function-name
./" Trace a specific function.


.PP
Options that tune execution
.TQ
.B "--enable-capabilities-cache, --disable-capabilities-cache"
Enable or disable caching of capabilities strings, improving performance.
The default is
.B --enable-capabilities-cache
.TQ
.\" .B "--enable-displays-cache, --disable-displays-cache"
.\" Enable or disable caching of information about detected displays, improving performance.
.\" The default is 
.\".B "--enable-displays-cache"
.TQ
.B "--enable-dynamic-sleep, --disable-dynamic-sleep"
Dynamically adjust the sleep-multiplier over multiple \fBddcutil\fP invocations, improving performance. 
The default is
.B "--enable-dynamic-sleep"
.TQ
.BI "--min-dynamic-multiplier " "decimal number"
Modify the dynamic sleep algorithm to never adjust the sleep multiplier below this value.
This option can help dampen swings in sleep multiplier values.
.TQ
.BI "--sleep-multiplier " "decimal number"
Adjust the length of waits listed in the DDC/CI specification by this number to determine the actual 
wait time.  Well behaved monitors work with sleep-multiplier values less than 1.0, while monitors
with poor DDC implementations may require sleep-multiplier values greater than 1.0.  In general,
newer option \fB--enable-dynamic-sleep\fP will provide better performance.
.\" .TQ
.\" .B "--lazy-sleep"
.\" Peform mandated sleeps before the next DDC/CI operation instead of immediately after the
.\" DDC/CI operation that specified a delay, marginally improving performance.
.\" .TQ
.\" .B "--i2c-bus-checks-async-min"
.\" (experimental option) During display detection, examine I2C buses in parallel to see if a monitor is present.
.\" These are low level checks that do not test DDC communication. The default is
.\" .B "--i2c-bus-checks-async-min 99"
.\" (i.e. never).
.\" .TQ
.\" .B "--ddc-checks-async-min"
.\" If there are several monitors, initial DDC checks are performed in multiple threads, improving performance.
.\" This option was formerly (and ambiguously) named \fB--async\fP.  The default is 
.\" .B "--ddc-checks-async-min 3"
.TQ
.B "--skip-ddc-checks"
Assume DDC communication works and monitors properly use the invalid feature flag in a
DDC/CI Reply packet to indicate an unsupported feature, improving display detection performance.
.TQ
.B "--discard-cache [capabilities|dsa|all"
Discard cached display information and/or dynamic sleep data.

.PP
Options that modify behavior
.TQ
.BI "--maxtries " "(max-read-tries, max-write-read-tries, max-multi-part-tries)"
Adjust the number of retries.  A value of "." or "0" leaves the setting for a retry type unchanged.
.TQ
.B "--verify | --noverify"
Verify or do not verify values set by \fBsetvcp\fP or \fBloadvcp\fP. \fB--noverify\fP is the default.
.TQ
.BI "--mccs " "MCCS version"
Tailor command input and 
output to a particular MCCS version, e.g. 2.1
.TQ
.B "--enable-udf, --disable-udf"
Enable or disable support for user supplied feature definitions.
The default is
.B "--enable-udf"
.TQ
.B "--enable-usb, --disable-usb"
Enable or disable support for monitors that implement USB communication with the Virtual Control Panel.
(These options are available only if \fBddcutil\fP was built with USB support.)
The default is 
.B "--disable-usb"
.TQ
.BI "--ignore-usb-vid-pid " vid:pid
Force \fBddcutil\fP to ignore a particular USB device, specified by its 4 hex digit vendor id and its 4 hex digit product id.
.TQ
.BI "--ignore-hiddev " hiddev-device-number
Force \fBddcutil\fI to ignore a particular USB device, specified by /dev/usb/hiddev device number
.TQ
.BI "--use-file-io | --use-ioctl-io"
Cause \fBddcutil\fP to use the write()/read() interface or the ioctl interface of driver dev-i2c to send and receive I2C packets.
By default, \fBddcutil\fP uses the ioctl interface.  Nvidia proprietary
driver are built in a way such that the ioctl interface can fail, in which case \fBddcutil\fP switches to using the file io interface.
.TQ
.B "--force-slave-address"
Take control of slave addresses on the I2C bus even they are in use.
Has use only with file-io, not with ioctl-io. 
.TQ
.BI "--enable-cross-instance-locks | --disable-cross-instance-locks"
Coordinates /dev/i2c device access across multiple instance of \fBddcutil\fP and \fBlibddcutil\fP.
The default is
.B "--enable-cross-instance-locks"
.TQ
.BI "--edid-read-size " "128|256"
Force \fBddcutil\fP to read the specified number of bytes when reading the EDID.
This option is a work-around for certain driver bugs.
The default is 256.
.TQ
.BI "--i2c-source-addr " hex-addr
Use this as the source address in DDC packet, instead of the normal value.
This option has been found to enable access some control functions when using some displays, particularly from LG.
.TQ
.B "--permit-unknown-feature"
Allow \fBsetvcp\fP of unknown features.

.PP Miscellaneous
.TQ
.BI "--ignore-mmid " monitor-model-id
Ignore monitors with this monitor-model-id.  The see the monitor-model-id for a display, 
use command \fBddcutil --verbose\fP.
.TQ 
.BR "--noconfig "  
Do not process the configuration file


.\" .SH EXECUTION ENVIRONMENT 

.\" Requires read/write access to /dev/i2c devices.  See 
.\".UR http://www.ddcutil.com/i2c_permissions.
.\".UE

.SH NVIDIA PROPRIETARY DRIVER

Some Nvidia cards using the proprietary Nvidia driver require special settings to properly enable I2C support.  See 
.UR http://www.ddcutil.com/nvidia
.UE .


.SH VIRTUAL MACHINES

Virtualized video drivers in VMWare and VirtualBox do not provide I2C emulation.  Use of normal video drivers with PCI passthrough 
is possible.


.SH EXAMPLES
.\" What do .EX and .EE do?

.B ddcutil detect
.sp 0
Identify all attached monitors.
.sp 4
.B ddcutil getvcp supported
.sp 1
.br
Show all settings that the default monitor supports and that \fBddcutil\fP understands.
.PP
.sp 0
.B ddcutil getvcp 10 --display 2
.br
Query the luminosity value of the second monitor. 

.B   ddcutil setvcp 10 30 --bus 4
.sp 0
Set the luminosity value for the monitor on bus /dev/i2c-4. 

.B ddcutil vcpinfo --verbose
.sp 0
Show detailed information about VCP features that \fBddcutil\fP understands. 

.B ddcutil interrogate > ~/ddcutil.out 
.sp 0
Collect maximum information about monitor capabilities and the execution environment, and 
direct the output to a file.


.SH DIAGNOSTICS

Returns 0 on success, 1 on failure. 

Requesting help is regarded as success.

.\" .SH FILES



.SH SEE ALSO
.\" README file /usr/local/share/doc/ddcutil/README.md
.\" The program is documented fully in
.\" .br
.\" /usr/local/share/doc/ddcutil/html/index.html
.\" .PP
The project homepage: 
.UR http://www.ddcutil.com
.UE



.\" .SH NOTES


.\" .SH BUGS


.SH AUTHOR
Sanford Rockowitz (rockowitz at minsoft dot com)
.br
Copyright 2015\-2023 Sanford Rockowitz


